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Abstract 


This document provides implementation guidelines for the use of 
return codes in RFC 3435, Media Gateway Control Protocol (MGCP) 
Version 1.0. Return codes in RFC 3435 do not cover all possible 
specific situations that may ever occur in a gateway. That is not 
possible and not necessary. What is important is to ensure that the 
Call Agent that receives a return code behaves appropriately and 
consistently for the given situation. The purpose of this document 
is to provide implementation guidelines to ensure that consistency. 
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Introduction 


This document provides implementation guidelines for the use of 
return codes in the Media Gateway Control Protocol MGCP 1.0 [1]. 
Return codes in [1] do not cover all possible specific situations 
that may ever occur in the gateway. That is not possible and not 
necessary. What is important is to ensure that the Call Agent that 
receives that return code behaves appropriately and consistently for 
the situation that occurred. The solution described in this document 
is to categorize return codes that gateways return based on the 
expected behavior for the Call Agents that receive them. 


Categorizing errors helps both Call Agent and gateway developers: it 
helps gateway developers choose an appropriate return code when a 
specific one for the situation is not available; it also helps Call 
Agent developers ensure that there is consistent behavior for the 
return code that is received. 


.2. Document Organization 


In addition to categorizing return codes (section 2.1), section 2.2 
provides a consolidated list of return codes in terms of "situations" 
that may have triggered and the "categories" that they fall under. 
This provides some additional implementation guidelines for the use 
of these return codes. Section 2.3 includes a summary of the return 
codes and their categories. Section 3 provides some additional 
implementation guidelines for Call Agent and gateway developers. 


Return Code Usage 
1. Return Code Categories 


The following categorizes return codes from gateways based on 
expected Call Agent behavior. 


Category normal: These return codes are used in normal operation and 
do not represent error conditions. 


Category none (specific errors requiring specific action): A return 
code associated with a specific situation in the gateway that will 
invoke a corresponding specific Call Agent behavior. As such, 
these return codes are not categorized into a common behavioral 
category. 


Category "Service Failure": A category in which the endpoint is 
either out-of-service or the treatment by the Call Agent is 
expected to be the same as for an out-of-service endpoint. 
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Category "Provisioning Mismatch": A situation where the gateway has 
indicated that it does not support what the Call Agent has asked 
it to do. This may be caused by a lack of synchronization between 
the provisioning of the Call Agent and the gateway. Note that 
attempts should be made to weed out these types of error 
situations during integration testing. 


Category "Temporary Failure": The transient nature of this error is 
such that this particular call is likely to be permanently 
affected but later calls on the same endpoint may proceed 
successfully. Typically the situation that caused this error is 
not going to disappear unless there is some change in state in the 
gateway or network (e.g., more bandwidth becomes available, more 
CPU resources become available etc.). This situation is not 
likely to change in a few 10’s of milliseconds but could change 
within some number of seconds or minutes later (as resources 
become free), i.e., within the time period that you might expect a 
different call to be tried on that endpoint. 


Category "State Mismatch": A case where there is a state mismatch 
between the Call Agent and the gateway that can be resolved by the 
Call Agent making a request that is more appropriate to the 
gateway state. Although categorized with a common category 
indicator the behavior of the Call Agent will depend on the 
situation (the type of state mismatch that has occurred as well as 
other state information, e.g., call state). 


Category "Remote Connection Descriptor Error": This indicates some 
mismatch between the two gateways involved in the call. Note that 
per RFC 2327, all gateways should ignore SDP attributes that they 
do not recognize (i.e., lack of recognition of an SDP attribute 
should not be the cause of an error indication). 


The exact behavior of the Call Agent for the above categories may 
depend on the type of endpoint (analog, ISUP trunk, CAS trunk, etc.), 
whether this is the originating or terminating endpoint in the call 
and possibly other information related to call state. This document 
does not attempt to outline the Call Agent behavior based on call 
state. Instead, it just recommends that the Call Agent behavior be 
consistent based on a combination of call state and the specific 
category of error received. 


2.2. Return Code Situations and Categories 
This section describes return codes in MGCP 1.0 [1] in terms of 
"Situations" that may have triggered that return code and 


"categories" to which the return code belongs. The purpose is to 
provide developers additional guidelines for return code use. 
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Note that any indication that a response is valid for a 
NotificationRequest (RONT) is also an indication that it is valid for 
a connection handling request, i.e., CreateConnection (CRCX), 
ModifyConnection (MDCX), or DeleteConnection (DLCX) with an 
encapsulated RONT. The same holds for the EndpointConfiguration 
(EPCF) command. 


000 - Response acknowledgement 


Response valid for: Confirmation of a final response after a 
provisional response (3-way handshake). 


Situation: If the final response that follows a provisional 
response contains an empty response acknowledgement parameter, a 
Response Acknowledgement is used to acknowledge the final 
response (section 3.5.6 of [1]). 


Category: normal. 
100 - Transaction in progress 
Response valid for: Any command that may result in a long 


transaction execution time, e.g., more than 200 ms. 


Situation: When a transaction is expected to take a processing 
time that is beyond the normal retry timer, the gateway will 
return a provisional response. A final response will be 
provided later, after the transaction has completed. Refer to 
section 3.5.6 of [1]. An example of this might be a 
CreateConnection command using RSVP, where the time to create 
the connection may be longer than usual because of the need to 
perform the network resource reservation. 


Category: normal. 
101 - Transaction has been queued for execution 
Response valid for: Any command. 


Situation: As described in [1], Section 4.4.8, we assume that 
Call Agents and gateways conceptually maintain a queue of 
incoming transactions to be executed. Associated with this 
transaction queue is a high-water and a low-water mark. Once 
the queue length reaches the high-water mark, the entity should 
start issuing 101 provisional responses (transaction queued) 
until the queue length drops to the low-water mark. This 
applies to new transactions as well as to retransmissions. A 
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final response will be provided later, after the transaction has 
completed. In this case, the Call Agent should throttle back 
its request rate for this gateway. 


Category: normal. 

200 - Transaction executed normally 
Response valid for: Any command (including DeleteConnection). 
Situation: Normal response as a result of successful 


execution. The 250 response code can be used to acknowledge a 
successful completion of a DeleteConnection command. However, a 
200 response code is also appropriate. 
Category: normal 

250 - The connection was deleted 
Response valid for: DeleteConnection. 
Situation: Response to a successful DeleteConnection command. 
Category: normal 

400 - Unspecified transient error 
Response valid for: Any command. 
Situation: Unspecified transient error. A more specific error 
code should be used if one is available since this error code 
provides very little information. If used, some specific 
commentary should be included to aid in debug. 


Category: "Temporary Failure". 


401 - The phone is already off-hook 


Response valid for: NotificationRequest. 

Situation: This is returned in response to a request for an 
off-hook transition requested event when the phone is already 
off-hook. It is also returned when a request is made to 
generate a signal that has an explicit on-hook precondition in 
the signal definition, such as the ringing signal ("rg") in the 
Line package [2]. It is also returned when requesting an 
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incoming off-hook/seizure indication for a Channel Associated 
Signaling (CAS) trunk when the incoming hook-state for that 
trunk is already off-hook. 


Category: "State Mismatch". If the Call Agent makes the request 
with a requested event indicating a different hook-state, the 
request should not result in this return code again. 


402 - The phone is already on-hook 
Response valid for: NotificationRequest. 


Situation: This is returned in response to a request for an on- 
hook or hook-flash requested event when the phone is already 
on-hook. It is also returned when a request is made to generate 
a signal that has an explicit off-hook precondition in the 
signal definition, such as the dial tone ("dl") in the Line 
package [2]. It is also returned when requesting an incoming 
on-hook indication for a CAS trunk when the incoming hook-state 
for that trunk is already on-hook. 


Category: "State Mismatch". If the Call Agent makes the 
request with a requested event indicating a different hook- 
state, the request should not result in this error again. 


403 - Insufficient resources available at this time 
Response valid for: Any command. 
Situation: This is returned if the request cannot be processed 
due to a temporary lack of gateway resources, such as CPU 
utilization, DSP resources, memory etc; however, the command may 
succeed at a later time when resources free up. Note that lack 
of network resources should not result in this code (i.e., 
return code 404 would be more appropriate). 
Category: "Temporary Failure". 

404 - Insufficient bandwidth at this time. 
Response valid for: CreateConnection, ModifyConnection. 
Situation: This is an indication that there is not enough 
bandwidth available to sustain the call. It is as a result of 


some failed bandwidth check (could be RSVP or some other 
mechanism). It is possible that the Call Agent could request a 
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codec requiring lower bandwidth codec and have a successful 
result. Alternatively, it could treat this as a "Temporary 
Failure" for this codec. 


Category: "Temporary Failure". Although categorized under 
this general category, note that the Call Agent could apply some 
specific behavior (try a lower bandwidth codec) depending on 
policy. 


405 - Endpoint is restarting 
Response valid for: Any command. 


Situation: It may be returned to requests made when the 
endpoint is in-service and has initiated the restart procedures 
(see [1], Section 4.4.6) but the procedure has not yet 
completed. If the request is made at a later time, it may be 
"successful" but may not be appropriate (because of possible 
state mismatch). The Call Agent should proceed after it 
believes the restart procedure has completed. 


Category: "Temporary Failure" 
406 - Transaction Timeout 
Response valid for: Any command. 


Situation: The transaction took longer than expected and has 
been aborted. An example might be a transaction where a 
provisional response (100 response code) was returned. 

Following that, the gateway determined that the actual 
transaction was taking longer than should reasonably be expected 
and as a result it aborted the transaction and returned 406 as 
the final response. 


Category: "Temporary Failure". If this error code is 
returned repeatedly, it could indicate a more serious problem. 


407 - Transaction aborted by some external action. 
Response valid for: Any command. 
Situation: This is returned to indicate cancellation of a 
pending request (see [1] Section 4.4.4). For example, 


DeleteConnection is received while processing a CreateConnection 
or ModifyConnection. Also, if either a ModifyConnection, 
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NotificationRequest, or EndpointConfiguration command is in 
progress, and the same command is received with a different 
transaction Id, 407 will be returned. 


Category: none (specific situation and behavior). 
409 - Internal overload 
Response valid for: Any command. 


Situation: Gateway is overloaded (e.g., too many requests per 
second from the Call Agent) and is unable to process any more 
transactions at this time. In this case, the Call Agent SHOULD 
throttle back its request rate for this gateway as described in 
[1], Section 4.4.8. 


Category: "Temporary Failure". Note that although the Call 
Agent behavior with respect to the call being set up corresponds 
to this general category, there is some specific Call Agent 
behavior implied as well (i.e., the Call Agent throttling back). 


410 - No endpoint available 
Response valid for: CreateConnection using an "any of" wildcard. 


Situation: A CreateConnection request was made with an "any 
of" ("$") wildcard and no endpoint was available to execute the 
request. As described in [1], Section 2.3.5, when the "any of" 
wildcard is used with the CreateConnection command, the endpoint 
assigned MUST be in-service and MUST NOT already have any 
connections on it. 


Category: none (specific situation and behavior). 
500 - Endpoint unknown 
Response valid for: Any command. 


Situation: There is no endpoint matching the EndpointId 
provided with the command. This could be the result of a 
provisioning mismatch between the Call Agent and the gateway or 
it could be because a card was removed from the gateway so that 
the endpoint is no longer available (in which case a 
RestartInProgress should be received, although the Call Agent 
cannot depend on this). Note that the endpoint is not just out- 
of-service (in which case 501 would be used); it is completely 
unknown/unavailable to the MGCP. 
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Category: "Provisioning Mismatch". 
501 - Endpoint is not ready or is out of service 
Response valid for: Any command. 
Situation: This is returned if the endpoint is in a permanent 


"not ready" state. This includes maintenance states such as 
out-of-service. Note that an endpoint that has initiated the 
restart procedure is in-service, and hence should not use this 
return code, even if the restart procedure has not yet completed 
(see [1], Section 4.4.5). 


Category: "Service Failure". 
502 - Insufficient resources (permanent). 
Response valid for: Any command. 


Situation: This is returned when the endpoint does not have 
sufficient resources and future requests on this endpoint are 
expected to fail, meaning some resources dedicated to the 
endpoint are broken (e.g., return code 529 - "hardware failure" 
might be a more specific indication). For situations where 
resources may become available in the future (i.e., resources 
are pooled and not available at the present time), return code 
403 should be used instead. 


Category: "Service Failure". 
503 - "All of" wildcard too complicated. 
Response valid for: Any command. 
Situation: This is returned when the wildcard convention used 


in the request is understood, but the requested command cannot 
be processed with the specified wildcarding. An example of this 
would be a NotificationRequest with a request such that a 
failure would make it too difficult to roll back the state of 
all the endpoints to what they were prior to the request. 


Category: Normally treated as a "Provisioning Mismatch". Note 
however, that the Call Agent could treat it differently by 
recovering with some specific behavior (e.g., generate a number 
of individual requests without wildcards instead of a single one 
with the wildcard). 
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504 - Unknown or unsupported command. 
Response valid for: Any unknown command. 


Situation: A command was requested other than those specified 
in the MGCP specification [1], and the command is not supported. 


Category: "Provisioning Mismatch". 

505 - Unsupported remote connection descriptor. 
Response valid for: CreateConnection, ModifyConnection. 
Situation: One or more mandatory parameters or values in the 
RemoteConnectionDescriptor are not supported by the gateway. 
Note that, per [3], unsupported attribute lines must be ignored 
and hence should not result in any errors. 


Category: "Remote Connection Descriptor Error". 


506 - Inability to satisfy both local connection options and remote 
connection descriptor simultaneously. 


Response valid for: CreateConnection, ModifyConnection. 
Situation: The LocalConnectionOptions and 
RemoteConnectionDescriptor contain one or more mandatory 
parameters or values that conflict with each other and/or cannot 
be supported at the same time (except for codec negotiation 
failure - see error code 534). 

Category: "Remote Connection Descriptor Error". 

507 - Unsupported Functionality. Note that this error code SHOULD 
only be used if there is no other more specific error code for 
the unsupported functionality. 

Response valid for: Any command. 

Situation: Any situation where a request from the Call Agent 
is not supported by the gateway - beyond the situations already 
covered by other more specific return codes. 

Category: "Provisioning Mismatch". 


508 - Unknown or unsupported quarantine handling. 


Response valid for: NotificationRequest. 
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Situation: The endpoint does not support or does not recognize 
the requested quarantine handling. 

Category: "Provisioning Mismatch". 

509 - Error in RemoteConnectionDescriptor 
Response valid for: CreateConnection, ModifyConnection. 
Situation: There is a syntax or semantic error in the Remote 
Connection Descriptor. For example, there is no IP address for 
an RTP media stream. 
Category: "Remote Connection Descriptor Error". 

510 - Protocol error 
Response valid for: Any command. 
Situation: Some unspecified protocol error was detected. 
Gateways should use this error as a last resort since it 


provides very little information. If used, some specific 
commentary should be included to aid in debug. 


Category: "Provisioning Mismatch". 
511 - Unrecognized parameter extension. 
Response valid for: Any command. 
Situation: It is returned if the requested command contains an 
unrecognized mandatory parameter extension ("X+"). In MGCP 1.0, 


this specifically refers to unrecognized parameters, since other 
error codes are available for unrecognized connection modes 
(517), unrecognized packages (518), unrecognized local 
connection options (541), etc. 


Category: "Provisioning Mismatch". 

512 - Gateway not equipped to detect one of the requested events. 
Response valid for: NotificationRequest. 
Situation: A valid event was requested however the gateway is 
not equipped to detect this event (i.e., the package is only 
implemented partially). Of course, such an implementation would 


not conform to [1]. Note that if an invalid event was 
requested, i.e., an event not defined in the relevant package, 
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then error code 522 should be used. Also note, that if the 
package is unknown or unsupported, then error code 518 should be 
used. 


Category: "Provisioning Mismatch". 


513 - gateway is not equipped to generate one of the requested 
signals. 


Response valid for: NotificationRequest. 


Situation: A valid signal was requested, however the gateway is 
not equipped to generate this signal (i.e., the package is only 
implemented partially). Of course, such an implementation would 
not conform to [1]. Note that if an invalid signal was 
requested, i.e., a signal not defined in the relevant package, 
then error code 522 should be used. Also note, that if the 
package is unknown or unsupported, then error code 518 should be 
used. 


Category: "Provisioning Mismatch". 


514 - The gateway cannot send the specified announcement. 


Response valid for: NotificationRequest with a request for an 
announcement to be played. 


Situation: This is a specific situation with respect to 
playing announcements on an endpoint or connection associated 
with the endpoint. Error code 538 could be used instead. 
Category: "Provisioning Mismatch". 


515 - Incorrect connection-id. 


Response valid for: CreateConnection, ModifyConnection, 
DeleteConnection, NotificationRequest, AuditConnection. 


Situation: An unknown connection-id has been specified. It is 
possible that the connection has already been deleted. It 
should be noted that a connection-id can also supplied with 


events and signals (e.g., "S: L/rt@connId"). Note that a 
mismatch between connection-id and call-id should use error code 
516. 

Category: "State Mismatch". 
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516 - Unknown or incorrect call-id. 


Response valid for: ModifyConnection, DeleteConnection. 


Situation: Unknown call-id, or the call-id supplied is 
incorrect (e.g., connection-id not associated with this call- 
id). 
Category: "State Mismatch". 

517 - Invalid or unsupported mode. 
Response valid for: CreateConnection, ModifyConnection. 
Situation: This is returned if the command specifies a 
connection mode that the endpoint does not support (note that 
not all endpoints will support all modes). Note that if the 


unsupported mode is an extension connection mode, error code 518 
(unsupported package) should be used instead. 


Category: "Provisioning Mismatch". 

518 - Unsupported or unknown package. 
Response valid for: Any command 
Situation: A package name included in a request is not 
supported (or unknown). Note that the package name may be a 
prefix to an event or other things (e.g., a parameter) as 
defined in [1]. Note that it is recommended to include a 
PackageList parameter with a list of supported packages in the 
response. 
Category: "Provisioning Mismatch". 


519 - Endpoint does not have a digit map. 
Response valid for: NotificationRequest. 


Situation: Request was made to detect digits based on a digit 
map and the gateway does not have a digit map. 


Category: "State Mismatch". The Call Agent needs to send 
down a digit map in order to continue with the call. 
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520 - Endpoint is restarting. 


Situation: This is normally a transient error in which error 
code 405 SHOULD be used. Gateways SHOULD not use this error 
code unless there is some relevant situation that warrants the 
category of "Service Failure". Note that this was included in 
[1] only to maintain backwards compatibility with previous 
releases of the MGCP specification. 


Category: If it is returned, this return code will be treated 
as category "Service Failure", i.e., as if this endpoint is 
out-of-service. 


521 - Endpoint re-directed to another Call Agent. 
Response valid for: RestartInProgress. 


Situation: A RestartInProgress command was sent to the Call 
Agent and the Call Agent returns this return code along with a 
NotifiedEntity parameter pointing to another Call Agent. The 
gateway then sends a new RestartInProgress command to the Call 
Agent specified in the Notified Entity. 


Category: none (specific situation and behavior). 
522 - No such event or signal. 
Response valid for: NotificationRequest. 


Situation: This is returned if the requested event/signal name 
is not registered with this package. If on the other hand the 
signal or event is part of the package but is not supported by 
the gateway, then return code 512 or 513 SHOULD be provided 
instead. If the package is not supported, return code 518 
SHOULD be returned. 


Category: "Provisioning Mismatch". 
523 - Unknown action or illegal combination of actions. 


Response valid for: NotificationRequest with one or more 
requested events. 


Situation: Request was made with a requested event(s) that 
included an action or actions defined in [1] that are either 
unknown, unsupported or an illegal combination as indicated in 
section 2.3.3 of [1]. Note that unsupported extension actions 
should generate error code 518 (unsupported package). 
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Category: "Provisioning Mismatch". 
524 - Internal inconsistency in Local Connection Options 
Response valid for: CreateConnection, ModifyConnection. 


Situation: This is returned if one or more of the 
LocalConnectionOptions (LCO) parameters are coded with values 
that are not consistent with each other (e.g., other LCO 
parameters inconsistent with the network type). 


Category: "Provisioning Mismatch". 
525 - Unknown extension in Local Connection Options. 
Response valid for: CreateConnection, ModifyConnection. 


Situation: This is returned if the request contains a Local 
Connection Option with one or more unrecognized mandatory ("x+") 
extensions. Note that unsupported package extensions should use 
error code 518 (unsupported package) instead. 


Category: "Provisioning Mismatch". 
526 - Insufficient bandwidth 
Response valid for: CreateConnection, ModifyConnection. 


Situation: In most cases where there is insufficient 
bandwidth, a 404 return code should be used. 526 would be used 
in cases where future requests are destined to fail. An example 
might be a very restricted bandwidth case, where there is not 
enough bandwidth available for the codec requested even for a 
single endpoint. Making a request with the same codec in the 
future will fail. However, making a request for some other 
codec (with a higher degree of compression) may pass. For 
cases, where the bandwidth is pooled over multiple endpoints and 
could free up at some future time (because an endpoint becomes 
inactive), then 404 is more appropriate. 


Category: If it is returned, this return code will be treated 
as category "Provisioning Mismatch", e.g., the codec was 
incorrectly provisioned for the bandwidth available. 


527 - Missing RemoteConnectionDescriptor. 


Response valid for: CreateConnection, ModifyConnection, 
NotificationRequest. 
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Situation: This is returned if the connection has not yet 
received a RemoteConnectionDescriptor when one is required to 
support the request. This can for example happen if a 
connection is attempted to be placed in "send/receive mode", or 
if a signal is applied on a connection. 


Category: "Remote Connection Descriptor Error" in the case 
where the other end did not provide a connection descriptor. 
Alternatively, if this is an initial request made by a Call 
Agent (such there is no remote connection descriptor), then this 
is a "State Mismatch" problem. 

528 -Incompatible protocol version 


Response valid for: Any command. 


Situation: A command was received with a protocol version that 
was not supported. 


Category: "Provisioning Mismatch". This could also be 
treated as a "State Mismatch" problem if the there is a recovery 
mechanism (e.g., Call Agent recognizes the protocol version 
mismatch and switches to the correct protocol version) 

529 - Internal Hardware Error. 
Response valid for: Any command. 
Situation: A hardware fault occurred during the execution of a 
command such that repeating this command will result ina 
failure indication once again. This is a slightly more specific 
error code than error 502, although more commentary should be 
provided (for debug purposes) if possible. 
Category: "Service Failure". 

530 - CAS Signaling Protocol Error. 
Response valid for: NotificationRequest. 
Situation: This is specific to Channel Associated Signaling 
(CAS) interfaces. A typical example might be an attempt to 


outpulse digits failed for some reason. 


Category: none (specific situation and behavior). 
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531 - Failure of a grouping of trunks (e.g., facility failure) 


Response valid for: CreateConnection, ModifyConnection, 
NotificationRequest. 


Situation: Request made to an endpoint that has a failed trunk 
connection (e.g., Tl or El failed). Note that an RSIP should 
have been sent as a result of the facility failure. This is a 


more specific response than return code 501. 
Category: "Service Failure". 

532 - Unsupported value(s) in Local Connection Options. 
Response valid for: CreateConnection, ModifyConnection. 
Situation: This is returned if one or more of the 


LocalConnectionOptions parameters are coded with a value that 
the gateway does not support. 


Category: "Provisioning Mismatch". 
533 - Response too large 
Response valid for: Any command. 


Situation: This would only be likely to occur in the case of an 
audit where the maximum response packet size would end up being 
too large. 


Category: none (specific situation and behavior). 
534 - Codec negotiation failure 
Response valid for: CreateConnection, ModifyConnection. 


Situation: The intersection between the list of codecs that 
the gateway supports, the codecs allowed by the local connection 
options and the codecs supplied in the Remote Connection 
Descriptor (if provided) is empty. 


Category: "Provisioning Mismatch" if the error resulted from 
an empty approved list of codes as described in [1], Section 
2.6). "Remote Connection Descriptor Error" if the error 
resulted from an empty negotiated list of codecs, as described 
in [1], Section 2.6. 
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535 - Packetization period not supported 
Response valid for: CreateConnection, ModifyConnection. 
Situation: Normally this error should not be generated since 


if the gateway is unable to support the packetization period 
specified in the local connection options for the codec 


indicated, it should follow the behavior specified in [1] (which 
is to pick an appropriate value rather than failing the 
request). 

Category: "none". 


536 - Unknown or unsupported Restart Method 
Response valid for: RestartInProgress. 


Situation: This error is generated by the Call Agent if it 
receives a RestartInProgress command with an unsupported restart 
method. Note that if the restart method is an extension restart 
method, error code 518 (unsupported package) should be used 


instead. 
Category: "Provisioning Mismatch". 
537 - Unknown or unsupported digit map extension 


Response valid for: NotificationRequest. 
Situation: Digit map letter in the digit map unknown or 
unsupported. Note that this code does apply to extension digit 
map letters as well. 
Category: "Provisioning Mismatch". 

538 - Event/signal parameter error 
Response valid for: NotificationRequest. 
Situation: It is returned if the event/signal parameter is in 
error or not supported. If the event/signal or a package is not 
supported, then one of 512, 513, 518, or 522 should be used 


instead. 


Category: "Provisioning Mismatch". 


Foster & Sivachelvan Informational [Page 18] 


RFC 3661 MGCP Return Code Usage December 2003 


539 - Invalid or unsupported command parameter 
Response valid for: Any command. 


Situation: This is returned if the command contains an invalid 
or unsupported parameter, which is neither a package (which 
would use return code 518) nor vendor specific extension (which 
would use return code 511). For example, if an endpoint does 
not support the BearerInformation parameter of the 
EndpointConfiguration command, this return code could be used. 
Of course, such an implementation would not conform to [1]. 


Category: "Provisioning Mismatch". 
540 - Per endpoint connection limit exceeded 


Response valid for: CreateConnection. 


Situation: A CreateConnection command was made, but the 
gateway cannot support any additional connections on that 
endpoint. 
Category: "State Mismatch". 

541 - Invalid or unsupported Local Connection Options 
Response valid for: CreateConnection, ModifyConnection. 
Situation: This is returned if the command contains an invalid 


or unsupported LocalConnectionOption, which is neither a package 
(which would use return code 518) nor vendor specific extension 
(which would use return code 511). 
Category: "Provisioning Mismatch". 
2.3. Summary of Return Code Categories 
A summary of the categories of the various error codes is included in 


the following table. This information is also repeated in the 
detailed error descriptions in the next section. 
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| Category | Return Codes 
| normal | 000, 100, 101, 200, 250 | 
a lst seas Seas N tee | 
| none | 405, 407, 410, 510, 521, 530, 533, 535 | 
a EEA | 
| "Service | 501, 502, 520, 529, 531 
| Failure" | 
|"Provisioning| 500, 503%, 504, 507, 508, 510, 511, 512, 513, 514, | 
| Mismatch" | S17, -S18; 522, 523, 524, 525; 526, 528"), 532).534%,.)| 
| | 536,539 a 538; 539, 54] | 
ae RIE | 
| "Temporary | 400, 403, 404*, 405, 406, 409 
| Failure" | 
| "State | 401, 402, 515, 516, 519, 540 | 
| Mismatch" | | 
33 [SSeS sate Se tee sen SSG USS sposi eles tate | 
| "Remote | 505, 506, 509; 527% 

Connection 

Descriptor 
| Error" | | 
Notes 


* 404: may be treated as a "Temporary Failure", but specific 
behavior is possible (e.g., trying an alternate codec with lower 
bandwidth requirement rather than failing this call). 


* 503: rather than treating this as a "Provisioning Mismatch", it is 
possible for the Call Agent to recover from this error. 


* 527: See the detailed description for this error code in section 
2.2. This could be treated as a "State Mismatch" depending on the 
circumstances. 


* 528: See the detailed description for this error code in section 
2.2. This could be treated as a "State Mismatch" depending on the 
circumstances. 


* 534: See the note on error code 534 in the detailed description 
section (2.2) of this document (may be treated as a "Remote 
Connection Descriptor Error" if no local connection options were 
supplied). 
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3. Additional Guidelines 


This section provides additional guidelines to Gateway and Call Agent 
developers. 


3.1. Gateway Recommendations 
The following guidelines are recommended for gateway implementations: 


* For uncategorized return codes (category "none") that involve 
specific situations, gateways should make sure they do an accurate 
mapping between the situation and the return code. 


* Also for category "State Mismatch", it is equally important that 
the situation (and state) is accurately mapped to the specific 
error code. 


* For situations similar to those involving return codes in "Service 
Failure", Provisioning Mismatch", "Temporary Failure" and "Remote 
Connection Descriptor Error" categories, the gateway should make 
sure that it uses a return code in the correct category. 


* MGCP allows additional commentary to be included with the return 
code. It is important that the gateway includes more specific 
information concerning the situation for debug purposes. 


* It is recommended that return codes 502, 520 and 526 not be used 
unless there is something that makes these permanent situations. 
As indicated in the detailed description of these return codes, 
403, 405 and 404 respectively are more appropriate in almost all 
situations. If a gateway presently uses 502, 520 and 526 for 
temporary situations and expects to upgrade to 403, 405 and 404, 
the gateway should refrain from using 502, 520 and 526 for some 
other use immediately after the upgrade. This is to avoid problems 
where a Call Agent is expected to treat the same error code in two 
different ways, e.g., 403 is a category "Temporary Failure" which 
requires a different Call Agent behavior from 502 which is in 
category "Service Failure". 


3.2. Call Agent Recommendations 
The following guidelines are recommended for gateway implementations: 
* Call Agents should handle return codes they do not recognize (or 


do not expect) based on the first digit in the return code as 
outlined in [1]. 
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* For categories "Service Failure", "Provisioning Mismatch", 
"Temporary Failure", and "Remote Connection Descriptor Error", 
Call Agents are expected to treat return codes that are within the 
same category in the same way (i.e., make the same decision, based 
on the return code and other state information available to them). 


* Because there was little guidance given for return codes 502, 520 
and 526 in RFC 2705 [4], Call Agents may have to treat these as 
403, 405 and 404 respectively for gateways that have not been 
updated according to [1] and these recommendations. The gateway 
implementer should be consulted for information on the gateway 
behavior for (now and in the future) for these return codes (i.e., 
it may be that return codes 502, 520 and 526 are presently used 
incorrectly but will be replaced with 403, 405 and 404 in the 
future). 


4. Security Considerations 
This document merely provides a convenient way to categorize MGCP 
return codes in order to facilitate decisions related to failure 


conditions; it does not impact MGCP security in any way. 
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This document and translations of it may be copied and furnished to 
others, and derivative works that comment on or otherwise explain it 
or assist in its implementation may be prepared, copied, published 
and distributed, in whole or in part, without restriction of any 
kind, provided that the above copyright notice and this paragraph are 
included on all such copies and derivative works. However, this 
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"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 
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